/**
 * @file    configuration.h
 * @brief   Documentation: How to configure WOSH Framework
 ****************************************************************************
 * @author  Alessandro Polo
 * @version 0.8.499 $Id: configuration.h 2861 2010-08-07 02:42:53Z alex $
 ****************************************************************************/
/* Copyright (c) 2007-2010, WOSH - Wide Open Smart Home 
 * by Alessandro Polo - OpenSmartHome.com
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above copyright
 *       notice, this list of conditions and the following disclaimer in the
 *       documentation and/or other materials provided with the distribution.
 *     * Neither the name of the OpenSmartHome.com WOSH nor the
 *       names of its contributors may be used to endorse or promote products
 *       derived from this software without specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED BY Alessandro Polo ''AS IS'' AND ANY
 * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
 * WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
 * DISCLAIMED. IN NO EVENT SHALL Alessandro Polo BE LIABLE FOR ANY
 * DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
 * LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 * SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 ****************************************************************************/

/*! \page page_config Configuration
 *
 * This page explains how to configure WOSH on your system.
 *
 * \note
 *  The configuration process is implemented within each WOSH Application.
 *  Because of that, it may change or even break the standard.
 *  Official \ref page_applications "WOSH Applications" share the
 *  same strategy and format, as described further in this page.
 *
 * \section page_config_toc Table of Contents:
 *
 *  - \ref page_config_overview
 *
 *  - \ref page_config_woshconf
 *  - \ref page_config_bundles
 *
 *  - \ref page_config_database
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_config_overview Overview
 *
 * WOSH system is made of a lot of components, their settings may be configured during
 * initialization or at run-time and are based on wosh::Property object.
 * Each component (such a core-module or a wosh::Bundle) is referred as a setting group,
 * stored by a set of wosh::PropertiesProvider object in wosh::Settings class.
 *
 * \ref page_applications load (and parse) configuration files into WoshKernel::settings()
 * instance, which will be inspected by components on their initialization.
 *
 * WOSH settings are stored in folder <a href="../../etc/wosh/">/etc/wosh/</a>.
 *
 * WOSH database files (building, automations, users, ..) are not considered part of the
 * system configuration and they are stored in <a href="../../var/database/">/var/database/</a>
 * folder (often in a specific sub-directory).
 *
 * Main configuration file should be located in \b "/etc/wosh/wosh.APPLICATION.conf",
 * it is the first file being loaded and usually defines only wosh::WoshKernel and \ref CoreModules settings,
 * although it may define settings (not \c directives, see further) of any bundle.
 *
 * WOSH Bundles are configured (and selected) using the \c apache2 strategy.
 *
 * As user, you need to know only where configuration files are located and
 * how they are interpreted (syntax).
 *
 * After loading the main configuration file, \ref page_applications load any \b *.conf file from folder
 * <a href="../../etc/wosh/bundles-enabled">/etc/wosh/bundles-enabled</a> by default (it may be customized)
 * (using wosh::Settings::loadConfigurationFolder() method).
 *
 * These settings are grouped pairs of \c key => \c value, each group refer to a component.
 *
 * WOSH may be instructed to load a set of built-in bundles (or dynamically),
 * this is managed by wosh::BundleManager and some custom \c directives.
 *
 * wosh::BundleManager and wosh::BundleLoader will analyze \b *.load files from folder
 * <a href="../../etc/wosh/bundles-enabled">/etc/wosh/bundles-enabled</a>.
 *
 * \note
 *  Configuration (.conf) and loading (.load) files, as \b wosh.conf are formatted
 *  as POSIX standard (same as INI format on Windows).
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_config_woshconf wosh.conf
 *
 * By default, \c wosh.conf contains some Kernel settings and directives, the
 * most important configuration key is \c WoshKernel::Name.
 * It must be unique in the network.
 *
 * In order to load XML databases and to enable networking, some custom settings are required.
 * 
 * Please refer to wosh::Settings documentation for syntaxt and data format.
 *
 * \warning
 *  Configuration file <tt>/etc/wosh/wosh.conf</tt> is usually \b missing or mis-configured.
 *  Even if it is included in the distribution, you should really take a look and update it.
 *
 * A sample configuration file is provided <a href="../../etc/wosh/wosh.default.conf">/etc/wosh/wosh.default.conf</a>.
 * Prompted here:
 * \include /etc/wosh/wosh.default.conf
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_config_bundles Bundles configuration
 *
 * Bundles are services (or components) of the WOSH system.
 * You may see them as applications running over WOSH layer, because of that they also (may) need
 * to be configured by custom settings. Moreover since most WOSH Applications are able to load
 * services dynamically (at boot), user have to select which bundles should be selected and started.
 *
 * You may read \ref page_bundles for more technical information.
 *
 * Bundles need to be loaded (created), configured (apply settings) and eventually started.
 * This process is managed by wosh::BundleManager and its helpers (such as wosh::BundleLoader),
 * but applications may manually allocate, configure and install a generic object into WOSH.
 *
 * Configuration works as Kernel and Core-Modules. Directives are (scheduled) actions
 * to be executed at boot-init (by wosh::BundleManager), the two fundamental actions are
 * \c BundleLoad and \c BundleStart.
 *
 * Bundle's configuration (settings) and directives (\c load/start) are placed by default
 * in the same folder as two different files. (<a href="../../etc/wosh/bundles-enabled">/etc/wosh/bundles-enabled</a>)
 *
 * User may change the path in the main configuration file (wosh.conf):
 *  - \b BundleLoadFolder in \c BundleManager group
 *  - \b BundleConfigFolder in \c BundleManager group
 *
 * As said, the configuration/loading strategy is very similar to apache2 (I find it amazing),
 * default configuration/loading files (the ones you take as template) are located in
 * <a href="../../etc/wosh/bundles-available">/etc/wosh/bundles-available</a> folder.
 *
 * On initialization, wosh::BundleManager loads the configuration folder ( \c BundleConfigFolder )
 * and adds settings-groups (there should be one for each bundle) to global settings-database (into
 * WoshKernel).
 *
 * Then, if \c AutoLoadBundles flag is enabled (default), it will parse \c BundleLoadFolder folder
 * and enqueue the actions (alphanumerical-ordered by their source filename).
 * Moreover all LOAD action will be executed. A LOAD action is formatted as:
 * \verbatim
BundleLoad wosh::interfaces::services::Discovery
\endverbatim
 * where \c wosh::interfaces::services::Discovery is the \b (class) \c Type of the Bundle, the name
 * of the object (bundle) will be set as default ('Discovery' in this example).
 *
 * Since there may be more instances of some type of bundles, you may assign its name (and
 * you must do it here) using the syntax:
  * \verbatim
BundleLoad wosh::interfaces::devices::PlayerGStreamer PlayerKitchen
\endverbatim
 * this will create a \c wosh::interfaces::devices::PlayerGStreamer bundle and assign the name \b PlayerKitchen
 *
 * Once bundles are loaded, BundleManager will forward their settings (Properties)
 * as defined (grouped) in global settings (which were loaded in previous step).
 *
 * wosh::BundleManager is ready to start bundles for you if the \c AutoStartBundles
 * flag is enabled. Executing START action as:
  * \verbatim
BundleStart PlayerDoccia
\endverbatim
 * Again, the action is not performed while parsing, but is delayed and
 * the iteration is ordered as the loading process (by filename).
 *
 * Some more notes:
 *  - Configuration(s) is not related to its source file, you may define multiple groups
      in a single configuration file and name it as you like.
 *
 *  - Each configuration section (group) refers to Bundle's \b Name (not its Type).
 *
 *  - Loading directives may be placed anywhere, you may care only of their order, but
 *    remember that the LOAD action are performed first and then, eventually START action
 *    will be executed (but again in a deterministic order).
 *
 * Final words.. configuration and loading filenames are standardized in WOSH, you should
 * follow the standard (similar to init.d of Linux systems).
  * \verbatim
<NUMBER:[0,999]>_<BUNDLE:TYPE(simplified)>.<EXTENSION{.conf;.load}>
\endverbatim
 * An example is \c 001_DiscoveryUdp.conf and 001_DiscoveryUdp.load
 * The number at the beginning let the user to easily insert and move items,
 * changing the start-up order of bundles (alphanumerical order).
 *
 * A sample Bundle's configuration file is prompted here
 * (<a href="../../etc/wosh/bundles-available/001_DiscoveryUdp.conf">/etc/wosh/bundles-available/001_DiscoveryUdp.conf</a>)
 * \include /etc/wosh/bundles-available/001_DiscoveryUdp.conf
 *
 * A sample Bundle's loading file is prompted here
 * (<a href="../../etc/wosh/bundles-available/001_DiscoveryUdp.load">/etc/wosh/bundles-available/001_DiscoveryUdp.load</a>)
 * \include /etc/wosh/bundles-available/001_DiscoveryUdp.load
 *
 * Loading and configuration of many bundles may also be grouped in two files,
 * as shown in <a href="../../etc/wosh/bundles-available/020_PlayerGStreamer.load">020_PlayerGStreamer.load</a>
 * and <a href="../../etc/wosh/bundles-available/020_PlayerGStreamer.conf">020_PlayerGStreamer.conf</a>.
 *
 * \note
 *  Log files may help you finding mis-configuration and detecting errors.
 *
 *
 * \htmlonly <hr/> \endhtmlonly
 ****************************************************************************
 * \section page_config_database Database
 *
 * While configuration files are global and 'read-only' (applied once, never overwritten),
 * there are also many other inputs (usually related to bundles). Some examples are:
 *  - Automations DB - defines automations (refer to wosh::services::TaskManagerBundle)
 *  - Building DB - defines building tree and properties (refer to wosh::services::BuildingManagerBundle)
 *  - Entertainment DB - defines multimedia zones, playlists (refer to wosh::services::MediaDirectorBundle)
 *  - Users DB - defines users' properties, groups (refer to wosh::UserManager)
 *
 * Default database folder is defined as \c $DATABASE (nested alias of \c $ROOT/var/database).
 *
 * \todo [..]
 *
 *
 ****************************************************************************
 *
 */
